This tutorial has two versions, Arexx and 'C'. The 'C' tutorial is after the Arexx one.
Before reading further, take a moment to run the tutorial so you understand what the program does.
TUTORIAL 2 ARexx
----------------
Now that we know how to designed a GUI we want to be able to operate one. To follow this example you need a basic knowledge of ARexx. Have a look at the file Tutorial2.rx in the demos drawer.
The program flow is straight forward. 3 simple steps.
1. Default values are set. These are the values of the gadgets when the GUI opens.
2. A routine (buildgui) is called to write the GUI definition to the pipe. (More on this routine later)
3. Events are read from the pipe and processed until the stream of events ends.
BUILDGUI
The 'buildgui' routine contains the information defining the GUI window and its gadgets. The data is sent line by line to the 'topipe' routine which sends the data to the pipe, checks for errors, and returns the GID returned by the pipe. (more on 'topipe' later.)
For most lines sent with 'topipe' the response is ignored. For gadget definitions however the return value is stored so we can identify gadget events later on.
TOPIPE
This routine takes a line of text and writes it to the pipe. The pipes response is read. If everything is ok the second parameter of the response is returned. This is the GID if a gadget is defined and a null string in most other cases. If an error occurs the problem line is output and the script exits.
You should use this routine or one like it when writing your own script for AWNPipe. It will help avoid common errors and make debugging much easier.
EVENT HANDLING
The main loop reads an event from the pipe and parses it into its parts. The first word of an event always tells the event type. This information is used to call a routine for that type of event.
CLOSE EVENT
If a close event is received write a little text and then exit the script.
GADGET EVENT
We check the second word of the event to see which gadget sent the event. For most gadgets we store event information and return. If the cancel gadget is the cause of the event we output some text and exit. If it was the done gadget we output the information for each gadget and exit. If it was the reset gadget we close the pipe, then create the gui again to restore the default values.
MENU EVENT
The second word of a menu event is the menu number, the third word id the item number, and the forth the subitem number. This information is used to determine what action should be taken in response to an event.
Almost any GUI can be operated using this approach demonstrated in this tutorial. Use these functions as building blocks in your own scripts.
TUTORIAL 2 in C
----------------
The files tutorial2.c and tutorial2 can be found in in the demos drawer.
Now that we know how to designed a GUI we want to be able to operate one. To follow this example you need a basic knowledge of 'C'. Have a look at the file Tutorial2.c in the demos drawer. We will examine each of the functions in detail since they will be useful building blocks for making other GUIs. There is only 1 interesting structure.
struct GUIpipe myGP
This structure is used to manage the GUI. It contains the GUIs file handle, error status,and read buffer. It as has storage for some useful data parsed from replies or events.
int main( int argc, char *argv[]);
The program flow is straight forward. Default values are set. We call a routine to build the GUI and operate the gui if we built it successfully. To operate the GUI we simply read events and react to them. Before we exit we make sure the GUIs filehandle is closed.
int getline(struct GUIpipe * GP);
We need to handle text one line at a time when operating the GUI. This routine reads the pipe making a sure a full line is available before returning. It will remove the previous line from the buffer first if there was one. We delimit the line with a null byte so we can use it as a string in other functions.
__stdargs int topipe(struct GUIpipe * GP, UBYTE * data,...)
Again and Again you will need to write a line to the pipe and read the response. This routine does that for you. It writes data to the pipe and then reads a reply from the pipe. The reply line is parsed, and an error is flagged if the first part of the reply is not 'ok'. We return the value of the second reply part if all is ok, return 0 if an error occurred.
topipe allows Printf like formatting of data written to the pipe (VFPrintf is used). The regular Printf formats are supported. This is not needed in this example but it will be very useful as we expand the program in the other tutorials.
int buildgui(struct GUIpipe * GP);
All the information that defines the GUI is contained in this function. It opens a filehandle on the AWNPipe device and returns an error if this fails. The window and gadget definitions are written to the pipe and the returned gadget ID's are stored. If all gadgets are created ok the window is opened. The final error status of the GUI is returned.
int getevent(struct GUIpipe * GP);
This routine reads a line from the pipe and parses it storing information about the event. It returns the error status of the pipe.
int gadgets(struct GUIpipe * GP);
int menu(struct GUIpipe * GP);
These routines look at the information parsed from the last event and take appropriate action depending which gadget or menu item was selected. Some times the gadget state information from the event is stored. Other times information is output to the user.
int gperror(struct GUIpipe * GP,int error);
When an error is detected while reading or writing to the pipe this routine is called. It sets the error status and alerts the user an error has occurred.
UBYTE * eventstr(struct GUIpipe * GP, int num);
Some fields in events , like string gadget contents, can contain spaces. This functions returns a pointer to the 'num' word of the event. Since the line is delimited by a null you can treat this as a string pointer. If the 'num' word is not found NULL is returned. The pointer is only valid until the next call to getline(), getevent(), or topipe().
Almost any GUI can be operated using this approach demonstrated in this tutorial.
